Skip to main content

State Management component

Definitions​

  • A state is a text file with a configuration of a service that can be shared between different units according to business rules.
  • A state ID is a unique identifier of a state, that might be shared between units.

Assumptions​

  • Set of subjects can be provided by AosCore/vendor and might differ on different unit types (Reported Subjects)
  • State ID bounds to a particular subject’s value (see Service Instance Management component). The following scenarios are supported:
    • The state ID is bound to a subject. In this case, the state shall migrate to any unit, managed by the same user (Actual Service State).
    • The state ID is bound to a unit (System ID). In this case, it will not migrate (Default Service State).
  • The state can be changed from a unit side only
  • Binding state id to any other subject is not supported yet
  • Only one unit with a particular state ID can be online at the same moment
  • Subject (non-group) - "Driver", "Passenger", services assigned to this subject, are related to a particular person. Subjects of this kind cannot be active from different units at the same time but can coexist with other subjects on the same unit. Services states are synced to the AosEdge Cloud
    • States modifications are synced to & from the Cloud (states are bound to subjects, not units)
  • Group Subject - subject to cover services related to a group of units, not related to a particular person. Can be several such subjects active from the same unit. This subject can be active on different units at the same time. Services states are not synced to the AosEdge Cloud
    • Service states are never synced to the AosEdge Cloud. The service state could be changed but the cloud will ignore the service state update
    • Service State can be setup from AosEdge Cloud
  • The typical state file size is around 50Kb

Sharing states between units​

Actually, there is a single flow supported for now. It is presented below.

Non-Group Subject​

Non-Group Subject

As the state can be bound to a user’s subject and shared between units within the same ID the idea is to upload it to the AosEdge Cloud on change and restore it on another unit.

Group Subject​

Group Subject

  • Service states are never synced to the AosEdge Cloud. The service state could be changed but the cloud will ignore the service state update
  • Service State can be setup from AosEdge Cloud as Default for all Group Subject where this service is attached

State update subflows​

There are two flows that force pushing states from AosEdge Cloud to a unit during unit connection:

  • The state update flow (only if Service is in Non-Group Subject)
  • The state force push flow Both of them extend the Unit connection flow. The diagram below provides more detail. State update subflows

Update state flow occurs if a checksum, sent in a Unit Status message for a particular service differs from a checksum stored on a AosEdge Cloud for a service’s state. However, the service state might not be applied, see "Concurrency and offline scenario" below.

Force Push scenario occurs if service provider forces uploading default state for all units for some reason (e.g. new service version was issued with incompatible changes in states). In this case, the AosEdge Cloud should send an Update State message immediately after sending the Desired Status message. the unit should be ready to handle this message at any moment.

The default state should be stored on blob storage, and the URL should be stored in the ServiceVersion table.

The following points should be taken into consideration:

  • Consider possible concurrency issues with state updating on the unit
  • Any states compatibility between service version are the responsibility of service providers
  • The “Apply state” activity, which includes fallback scenarios and concurrency handling is described below
  • States might be encrypted by service providers and processing of this is the responsibility of the service provider
  • Service states are never synced to the AosEdge Cloud

State upload subflow​

The AosEdge Cloud always reports to the unit if the state was accepted or not. The state might not be accepted for different reasons, such as quotas exceeding.

State upload subflow

Consider that the “the latest state always overwrites others” concurrency handling strategy is applied here, that is OK, considering the point that concurrent state update is not expected.

Correlation ids should be used for matching State Acceptance messages to related New State messages.

State size is a part of quotas management. AosEdge Cloud should verify sent file fits into quotas. If it is not - the state should be rejected. If the “useState” parameter in config.json is set to “false”, it means that no state is used for the service.

Fallback scenarios​

Services may not start on a unit for some reason. The whole service fallback approach is out of the scope of this document, however, the reason may be a corrupted state.

In this case, it is suggested to use the following fallback approach:

  • Send a State Request message with the “default” flag set to “false”. The server will send an Update State message with the latest saved state for this service. If this doesn’t help:
  • Send a State Request message with the “default” flag set to “true”. The server will send an Update State message with the default state for this service. If this doesn’t help:
  • Report the error.

Concurrency and the offline scenario​

For the uploading of new states only for Non-Group Subject scenario, the “the latest state always overwrites previous” concurrency handling strategy is applied here, which is OK, considering the point that concurrent state update is not expected. A checksum is used for state comparison. Checksum should be calculated as usual.

For downloading states to a unit, the general rule “the AosEdge Cloud has a newer state version” shall be applied, except for the “offline mode” scenario, which is the following:

The unit sends to AosEdge Cloud state with checksum 42

  • Unit goes offline
  • Unit changes the state to a newer one, with checksum 48
  • The unit can’t upload a new state
  • The unit goes online and reconnects to the cloud
  • The unit receives a legacy state version with checksum 42
  • State changes are lost

To handle this particular scenario as long, as handle natural state migration scenarios on the unit side, it is suggested to:

  • On a unit, store latest successfully sent state checksum(i.e. latest accepted state)
  • If the latest uploaded state checksum is equal to the checksum in the UpdateState message, the received message should be ignored (that means, the local state was changed when a unit was offline) and the latest state should be sent to the AosEdge Cloud
  • If the latest uploaded state checksum is not equal to the checksum in the UpdateState message, local should be overwritten(that means, the AosEdge Cloud has a newer state)

The activity diagram below summarizes described flow on Unit: activity diagram

State sending frequency​

It is assumed that states should be sent to AosEdge Cloud after each update and updates are quite rare(one per several hours). However, some services may break the scenario and send states, for instance, each second. Being deployed to thousands of units, they may cause network traffic overload. To handle such cases, it is suggested to extend the unit configuration file with the parameter “minSendPeriod”, which is responsible for the minimal interval for sending states to the AosEdge Cloud.